<!DOCTYPE html>
<html prefix="og: http://ogp.me/ns#">
<head>
  <meta charset="UTF-8">
  <title>Creating Packages</title>
  <link data-turbolinks-track="true" href="../../assets/application-b86a2086c99917c6bf2a9d74b4038381.css" media="all" rel="stylesheet" />
  <script data-turbolinks-track="true" src="../../assets/application-c3106c6fe52ccec6f26495730a478cca.js"></script>
  <meta content="authenticity_token" name="csrf-param" />
<meta content="yzXUiWH6GiCHbvbJOg7usjzA7LawyxwB+oJHEcWTOIM=" name="csrf-token" />
  <script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

  ga('create', 'UA-3769691-35', 'atom.io');
  ga('send', 'pageview');

</script>

  <meta property="og:url" content="https://atom.io/" />
<meta property="og:site_name" content="Atom" />
<meta property="og:title" content="A hackable text editor for the 21st Century" />
<meta property="og:description" content="At GitHub, we’re building the text editor we’ve always wanted: hackable to the core, but approachable on the first day without ever touching a config file. We can’t wait to see what you build with it." />
<meta property="og:type" content="website" />
<meta property="og:author" content='https://www.facebook.com/GitHub' />
<meta property="og:image" content="http://og.github.com/atom-logo/atom-logo@1200x1200.png" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="1200" />
<meta property="og:image" content="http://og.github.com/atom-mark/atom-mark@1200x630.png" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />

  <meta property="twitter:card" content="summary_large_image" />
<meta property="twitter:site" content="@AtomEditor" />
<meta property="twitter:creator" content='@github' />
<meta property="twitter:title" content="Atom" />
<meta property="twitter:description" content="A hackable text editor for the 21st Century" />
<meta property="twitter:image:src" content="http://og.github.com/atom-logo/atom-logo@1200x630.png" />
<meta property="twitter:image:width" content="1200" />
<meta property="twitter:image:height" content="630" />

  <link rel="shortcut icon" href="../../favicon.ico"/>
</head>
<body>

  <div class="footer-push">
    
    

    <header class="header">
  <div class="wrapper">
    <h1 title="Atom">
      <a href="../../index.html" class="logo"></a>
    </h1>

    <ul class="navigation">
      <li><a class="" href="../../packages.html">Packages</a></li>
      <li><a class="is-selected" href="../latest/index.html">Documentation</a></li>
      <li><a href="http://blog.atom.io">Blog</a></li>
      <li><a href="../../faq.html">FAQ</a></li>
      <li><a class="" href="http://atom.io/contact">Contact</a></li>
    </ul>
  </div>
</header>


    <div class="wrapper documents content-push">
  <div class="columns">
    <div class="column main-column markdown">
        <h1>
<a name="creating-packages" href="creating-a-package.html#creating-packages"></a>Creating Packages</h1>

<p>Packages are at the core of Atom. Nearly everything outside of the main editor
is handled by a package. That includes "core" pieces like the <a href="https://github.com/atom/tree-view">file tree</a>,
<a href="https://github.com/atom/status-bar">status bar</a>, <a href="https://github.com/atom/language-coffee-script">syntax highlighting</a>, and more.</p>

<p>A package can contain a variety of different resource types to change Atom's
behavior. The basic package layout is as follows:</p>

<pre lang="text"><code>my-package/
  grammars/
  keymaps/
  lib/
  menus/
  spec/
  snippets/
  stylesheets/
  index.coffee
  package.json
</code></pre>

<p>Not every package will have (or need) all of these directories.</p>

<p>We have <a href="your-first-package.html">a tutorial on creating your first package</a>.</p>

<p>There are also guides for converting <a href="converting-a-text-mate-bundle.html">TextMate bundles</a> and
<a href="converting-a-text-mate-theme.html">TextMate themes</a> so they work in Atom.</p>

<h2>
<a name="packagejson" href="creating-a-package.html#packagejson"></a>package.json</h2>

<p>Similar to <a href="http://en.wikipedia.org/wiki/Npm_(software)">npm packages</a>, Atom packages contain a <em>package.json</em> file
in their top-level directory. This file contains metadata about the package,
such as the path to its "main" module, library dependencies, and manifests
specifying the order in which its resources should be loaded.</p>

<p>In addition to the regular <a href="https://npmjs.org/doc/json.html">npm package.json keys</a> available, Atom
package.json files have their own additions.</p>

<ul>
<li>
<code>main</code> (<strong>Required</strong>): the path to the CoffeeScript file that's the entry point
to your package</li>
<li>
<code>stylesheets</code> (<strong>Optional</strong>): an Array of Strings identifying the order of the
stylesheets your package needs to load. If not specified, stylesheets in the
<em>stylesheets</em> directory are added alphabetically.</li>
<li>
<code>keymaps</code>(<strong>Optional</strong>): an Array of Strings identifying the order of the
key mappings your package needs to load. If not specified, mappings in the
<em>keymaps</em> directory are added alphabetically.</li>
<li>
<code>menus</code>(<strong>Optional</strong>): an Array of Strings identifying the order of
the menu mappings your package needs to load. If not specified, mappings
in the <em>menus</em> directory are added alphabetically.</li>
<li>
<code>snippets</code> (<strong>Optional</strong>): an Array of Strings identifying the order of the
snippets your package needs to load. If not specified, snippets in the
<em>snippets</em> directory are added alphabetically.</li>
<li>
<code>activationEvents</code> (<strong>Optional</strong>): an Array of Strings identifying events that
trigger your package's activation. You can delay the loading of your package
until one of these events is triggered.</li>
</ul><h2>
<a name="source-code" href="creating-a-package.html#source-code"></a>Source Code</h2>

<p>If you want to extend Atom's behavior, your package should contain a single
top-level module, which you export from <em>index.coffee</em> (or whichever file is
indicated by the <code>main</code> key in your <em>package.json</em> file). The remainder of your
code should be placed in the <code>lib</code> directory, and required from your top-level
file.</p>

<p>Your package's top-level module is a singleton object that manages the lifecycle
of your extensions to Atom. Even if your package creates ten different views and
appends them to different parts of the DOM, it's all managed from your top-level
object.</p>

<p>Your package's top-level module should implement the following methods:</p>

<ul>
<li><p><code>activate(state)</code>: This <strong>required</strong> method is called when your
package is activated. It is passed the state data from the last time the window
was serialized if your module implements the <code>serialize()</code> method. Use this to
do initialization work when your package is started (like setting up DOM
elements or binding events).</p></li>
<li><p><code>serialize()</code>: This <strong>optional</strong> method is called when the window is shutting
down, allowing you to return JSON to represent the state of your component. When
the window is later restored, the data you returned is passed to your
module's <code>activate</code> method so you can restore your view to where the user left
off.</p></li>
<li><p><code>deactivate()</code>: This <strong>optional</strong> method is called when the window is shutting
down. If your package is watching any files or holding external resources in any
other way, release them here. If you're just subscribing to things on window,
you don't need to worry because that's getting torn down anyway.</p></li>
</ul><h3>
<a name="simple-package-code" href="creating-a-package.html#simple-package-code"></a>Simple Package Code</h3>

<p>Your directory would look like this:</p>

<pre lang="text"><code>my-package/
  package.json
  index.coffee
  lib/
    my-package.coffee
</code></pre>

<p><code>index.coffee</code> might be:</p>

<pre lang="coffeescript"><div class="line"><span class="source coffee"><span class="variable assignment coffee"><span class="variable assignment coffee"><span>module.exports </span><span class="keyword operator coffee"><span>=</span></span></span></span><span> </span><span class="support function coffee"><span>require</span></span><span> </span><span class="string quoted double coffee"><span class="punctuation definition string begin coffee"><span>"</span></span><span>./lib/my-package</span><span class="punctuation definition string end coffee"><span>"</span></span></span></span></div></pre>

<p><code>my-package/my-package.coffee</code> might start:</p>

<pre lang="coffeescript"><div class="line"><span class="source coffee"><span class="variable assignment coffee"><span class="variable assignment coffee"><span>module.exports </span><span class="keyword operator coffee"><span>=</span></span></span></span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="meta function coffee"><span class="entity name function coffee"><span>activat</span><span class="entity name function coffee"><span>e</span></span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="meta inline function coffee"><span class="variable parameter function coffee"><span>(state)</span></span><span> </span><span class="storage type function coffee"><span>-&gt;</span></span></span><span> </span><span class="comment line number-sign coffee"><span class="punctuation definition comment coffee"><span>#</span></span><span> ...</span></span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="meta function coffee"><span class="entity name function coffee"><span>deactivat</span><span class="entity name function coffee"><span>e</span></span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="storage type function coffee"><span>-&gt;</span></span><span> </span><span class="comment line number-sign coffee"><span class="punctuation definition comment coffee"><span>#</span></span><span> ...</span></span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="meta function coffee"><span class="entity name function coffee"><span>serializ</span><span class="entity name function coffee"><span>e</span></span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="storage type function coffee"><span>-&gt;</span></span><span> </span><span class="comment line number-sign coffee"><span class="punctuation definition comment coffee"><span>#</span></span><span> ...</span></span></span></div></pre>

<p>Beyond this simple contract, your package has access to Atom's API. Be aware
that since we are early in development, APIs are subject to change and we have
not yet established clear boundaries between what is public and what is private.
Also, please collaborate with us if you need an API that doesn't exist. Our goal
is to build out Atom's API organically based on the needs of package authors
like you.</p>

<h2>
<a name="stylesheets" href="creating-a-package.html#stylesheets"></a>Stylesheets</h2>

<p>Stylesheets for your package should be placed in the <em>stylesheets</em> directory.
Any stylesheets in this directory will be loaded and attached to the DOM when
your package is activated. Stylesheets can be written as CSS or <a href="http://atom.io/docs/v0.60.0/but%20LESS%0Ais%20recommended">LESS</a>.</p>

<p>Ideally, you won't need much in the way of styling. We've provided a standard
set of components which define both the colors and UI elements for any package
that fits into Atom seamlessly. You can view all of Atom's UI components by opening
the styleguide: open the command palette (<code>cmd-shift-P</code>) and search for <em>styleguide</em>,
or just type <code>cmd-ctrl-G</code>.</p>

<p>If you <em>do</em> need special styling, try to keep only structural styles in the package
stylesheets. If you <em>must</em> specify colors and sizing, these should be taken from
the active theme's <a href="https://github.com/atom/atom-dark-ui/blob/master/stylesheets/ui-variables.less">ui-variables.less</a>. For more information, see the
<a href="theme-variables.html">theme variables docs</a>. If you follow this guideline, your package
will look good out of the box with any theme!</p>

<p>An optional <code>stylesheets</code> array in your <em>package.json</em> can list the stylesheets
by name to specify a loading order; otherwise, stylesheets are loaded
alphabetically.</p>

<h2>
<a name="keymaps" href="creating-a-package.html#keymaps"></a>Keymaps</h2>

<p>It's recommended that you provide key bindings for commonly used actions for
your extension, especially if you're also adding a new command:</p>

<pre lang="coffeescript"><div class="line"><span class="source coffee"><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>.tree-view-scroller</span><span class="punctuation definition string end coffee"><span>'</span></span></span><span class="keyword operator coffee"><span>:</span></span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>ctrl-V</span><span class="punctuation definition string end coffee"><span>'</span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>changer:magic</span><span class="punctuation definition string end coffee"><span>'</span></span></span></span></div></pre>

<p>Keymaps are placed in the <em>keymaps</em> subdirectory. By default, all keymaps are
loaded in alphabetical order. An optional <code>keymaps</code> array in your <em>package.json</em>
can specify which keymaps to load and in what order.</p>

<p>Keybindings are executed by determining which element the keypress occurred on. In
the example above, <code>changer:magic</code> command is executed when pressing <code>ctrl-V</code> on
the <code>.tree-view-scroller</code> element.</p>

<p>See the <a href="advanced/keymaps.html">main keymaps documentation</a> for more detailed information on
how keymaps work.</p>

<h2>
<a name="menus" href="creating-a-package.html#menus"></a>Menus</h2>

<p>Menus are placed in the <em>menus</em> subdirectory. By default, all menus are loaded
in alphabetical order. An optional <code>menus</code> array in your <em>package.json</em> can
specify which menus to load and in what order.</p>

<h3>
<a name="application-menu" href="creating-a-package.html#application-menu"></a>Application Menu</h3>

<p>It's recommended that you create an application menu item for common actions
with your package that aren't tied to a specific element:</p>

<pre lang="coffeescript"><div class="line"><span class="source coffee"><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>menu</span><span class="punctuation definition string end coffee"><span>'</span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="meta brace square coffee"><span>[</span></span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="meta brace curly coffee"><span>{</span></span></span></div><div class="line"><span class="source coffee"><span>    </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>label</span><span class="punctuation definition string end coffee"><span>'</span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>Packages</span><span class="punctuation definition string end coffee"><span>'</span></span></span></span></div><div class="line"><span class="source coffee"><span>    </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>submenu</span><span class="punctuation definition string end coffee"><span>'</span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="meta brace square coffee"><span>[</span></span></span></div><div class="line"><span class="source coffee"><span>      </span><span class="meta brace curly coffee"><span>{</span></span></span></div><div class="line"><span class="source coffee"><span>        </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>label</span><span class="punctuation definition string end coffee"><span>'</span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>My Package</span><span class="punctuation definition string end coffee"><span>'</span></span></span></span></div><div class="line"><span class="source coffee"><span>        </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>submenu</span><span class="punctuation definition string end coffee"><span>'</span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="meta brace square coffee"><span>[</span></span></span></div><div class="line"><span class="source coffee"><span>          </span><span class="meta brace curly coffee"><span>{</span></span></span></div><div class="line"><span class="source coffee"><span>            </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>label</span><span class="punctuation definition string end coffee"><span>'</span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>Toggle</span><span class="punctuation definition string end coffee"><span>'</span></span></span></span></div><div class="line"><span class="source coffee"><span>            </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>command</span><span class="punctuation definition string end coffee"><span>'</span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>my-package:toggle</span><span class="punctuation definition string end coffee"><span>'</span></span></span></span></div><div class="line"><span class="source coffee"><span>          </span><span class="meta brace curly coffee"><span>}</span></span></span></div><div class="line"><span class="source coffee"><span>        </span><span class="meta brace square coffee"><span>]</span></span></span></div><div class="line"><span class="source coffee"><span>      </span><span class="meta brace curly coffee"><span>}</span></span></span></div><div class="line"><span class="source coffee"><span>    </span><span class="meta brace square coffee"><span>]</span></span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="meta brace curly coffee"><span>}</span></span></span></div><div class="line"><span class="source coffee"><span class="meta brace square coffee"><span>]</span></span></span></div></pre>

<p>To add your own item to the application menu, simply create a top level <code>menu</code>
key in any menu configuration file in <em>menus</em>. This can be a JSON or <a href="https://github.com/atom/season">CSON</a> file.</p>

<p>The menu templates you specify are merged with all other templates provided
by other packages in the order which they were loaded.</p>

<h3>
<a name="context-menu" href="creating-a-package.html#context-menu"></a>Context Menu</h3>

<p>It's recommended to specify a context menu item for commands that are linked to
specific parts of the interface, like adding a file in the tree-view:</p>

<pre lang="coffeescript"><div class="line"><span class="source coffee"><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>context-menu</span><span class="punctuation definition string end coffee"><span>'</span></span></span><span class="keyword operator coffee"><span>:</span></span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>.tree-view</span><span class="punctuation definition string end coffee"><span>'</span></span></span><span class="keyword operator coffee"><span>:</span></span></span></div><div class="line"><span class="source coffee"><span>    </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>Add file</span><span class="punctuation definition string end coffee"><span>'</span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>tree-view:add-file</span><span class="punctuation definition string end coffee"><span>'</span></span></span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>.workspace</span><span class="punctuation definition string end coffee"><span>'</span></span></span><span class="keyword operator coffee"><span>:</span></span></span></div><div class="line"><span class="source coffee"><span>    </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>Inspect Element</span><span class="punctuation definition string end coffee"><span>'</span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>core:inspect</span><span class="punctuation definition string end coffee"><span>'</span></span></span></span></div></pre>

<p>To add your own item to the application menu simply create a top level
<code>context-menu</code> key in any menu configuration file in <em>menus</em>. This can be a
JSON or <a href="https://github.com/atom/season">CSON</a> file.</p>

<p>Context menus are created by determining which element was selected and
then adding all of the menu items whose selectors match that element (in
the order which they were loaded). The process is then repeated for the
elements until reaching the top of the DOM tree.</p>

<p>In the example above, the <code>Add file</code> item will only appear when the focused item
or one of its parents has the <code>tree-view</code> class applied to it.</p>

<h2>
<a name="snippets" href="creating-a-package.html#snippets"></a>Snippets</h2>

<p>An extension can supply language snippets in the <em>snippets</em> directory which
allows the user to enter repetitive text quickly:</p>

<pre lang="coffeescript"><div class="line"><span class="source coffee"><span class="string quoted double coffee"><span class="punctuation definition string begin coffee"><span>"</span></span><span>.source.coffee .specs</span><span class="punctuation definition string end coffee"><span>"</span></span></span><span class="keyword operator coffee"><span>:</span></span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="string quoted double coffee"><span class="punctuation definition string begin coffee"><span>"</span></span><span>Expect</span><span class="punctuation definition string end coffee"><span>"</span></span></span><span class="keyword operator coffee"><span>:</span></span></span></div><div class="line"><span class="source coffee"><span>    </span><span class="variable assignment coffee"><span class="variable assignment coffee"><span>prefix</span><span class="punctuation separator key-value"><span>:</span></span></span></span><span> </span><span class="string quoted double coffee"><span class="punctuation definition string begin coffee"><span>"</span></span><span>ex</span><span class="punctuation definition string end coffee"><span>"</span></span></span></span></div><div class="line"><span class="source coffee"><span>    </span><span class="variable assignment coffee"><span class="variable assignment coffee"><span>body</span><span class="punctuation separator key-value"><span>:</span></span></span></span><span> </span><span class="string quoted double coffee"><span class="punctuation definition string begin coffee"><span>"</span></span><span>expect($1).to$2</span><span class="punctuation definition string end coffee"><span>"</span></span></span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="string quoted double coffee"><span class="punctuation definition string begin coffee"><span>"</span></span><span>Describe</span><span class="punctuation definition string end coffee"><span>"</span></span></span><span class="keyword operator coffee"><span>:</span></span></span></div><div class="line"><span class="source coffee"><span>    </span><span class="variable assignment coffee"><span class="variable assignment coffee"><span>prefix</span><span class="punctuation separator key-value"><span>:</span></span></span></span><span> </span><span class="string quoted double coffee"><span class="punctuation definition string begin coffee"><span>"</span></span><span>de</span><span class="punctuation definition string end coffee"><span>"</span></span></span></span></div><div class="line"><span class="source coffee"><span>    </span><span class="variable assignment coffee"><span class="variable assignment coffee"><span>body</span><span class="punctuation separator key-value"><span>:</span></span></span></span><span> </span><span class="string quoted double heredoc coffee"><span class="punctuation definition string begin coffee"><span>"""</span></span></span></span></div><div class="line"><span class="source coffee"><span class="string quoted double heredoc coffee"><span>      describe "${1:description}", -&gt;</span></span></span></div><div class="line"><span class="source coffee"><span class="string quoted double heredoc coffee"><span>        ${2:body}</span></span></span></div><div class="line"><span class="source coffee"><span class="string quoted double heredoc coffee"><span>    </span><span class="punctuation definition string end coffee"><span>"""</span></span></span></span></div></pre>

<p>A snippets file contains scope selectors at its top level (<code>.source.coffee
.spec</code>). Each scope selector contains a hash of snippets keyed by their name
(<code>Expect</code>, <code>Describe</code>). Each snippet also specifies a <code>prefix</code> and a <code>body</code> key.
The <code>prefix</code> represents the first few letters to type before hitting the <code>tab</code>
key to autocomplete. The <code>body</code> defines the autofilled text. You can use
placeholders like <code>$1</code>, <code>$2</code>, to indicate regions in the body the user can
navigate to every time they hit <code>tab</code>.</p>

<p>All files in the directory are automatically loaded, unless the <em>package.json</em>
supplies a <code>snippets</code> key. As with all scoped items, snippets loaded later take
precedence over earlier snippets when two snippets match a scope with the same
specificity.</p>

<h2>
<a name="language-grammars" href="creating-a-package.html#language-grammars"></a>Language Grammars</h2>

<p>If you're developing a new language grammar, you'll want to place your file in
the <em>grammars</em> directory. Each grammar is a pairing of two keys, <code>match</code> and
<code>captures</code>. <code>match</code> is a regular expression identifying the pattern to
highlight, while <code>captures</code> is an object representing what to do with each
matching group.</p>

<p>For example:</p>

<pre lang="coffeescript"><div class="line"><span class="source coffee"><span class="meta brace curly coffee"><span>{</span></span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>match</span><span class="punctuation definition string end coffee"><span>'</span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>(?:^|</span><span class="constant character escape coffee"><span>\\</span></span><span>s)(__[^_]+__)</span><span class="punctuation definition string end coffee"><span>'</span></span></span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>captures</span><span class="punctuation definition string end coffee"><span>'</span></span></span><span class="keyword operator coffee"><span>:</span></span></span></div><div class="line"><span class="source coffee"><span>    </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>1</span><span class="punctuation definition string end coffee"><span>'</span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>name</span><span class="punctuation definition string end coffee"><span>'</span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>markup.bold.gfm</span><span class="punctuation definition string end coffee"><span>'</span></span></span></span></div><div class="line"><span class="source coffee"><span class="meta brace curly coffee"><span>}</span></span></span></div></pre>

<p>This indicates that the first matching capture (<code>(__[^_]+__)</code>) should have the
<code>markup.bold.gfm</code> token applied to it.</p>

<p>To capture a single group, simply use the <code>name</code> key instead:</p>

<pre lang="coffeescript"><div class="line"><span class="source coffee"><span class="meta brace curly coffee"><span>{</span></span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>match</span><span class="punctuation definition string end coffee"><span>'</span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>^#{1,6}</span><span class="constant character escape coffee"><span>\\</span></span><span>s+.+$</span><span class="punctuation definition string end coffee"><span>'</span></span></span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>name</span><span class="punctuation definition string end coffee"><span>'</span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>markup.heading.gfm</span><span class="punctuation definition string end coffee"><span>'</span></span></span></span></div><div class="line"><span class="source coffee"><span class="meta brace curly coffee"><span>}</span></span></span></div></pre>

<p>This indicates that Markdown header lines (<code>#</code>, <code>##</code>, <code>###</code>) should be applied
with the <code>markup.heading.gfm</code> token.</p>

<p>More information about the significance of these tokens can be found in
<a href="http://manual.macromates.com/en/language_grammars.html">section 12.4 of the TextMate Manual</a>.</p>

<p>Your grammar should also include a <code>filetypes</code> array, which is a list of file
extensions your grammar supports:</p>

<pre lang="coffeescript"><div class="line"><span class="source coffee"><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>fileTypes</span><span class="punctuation definition string end coffee"><span>'</span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="meta brace square coffee"><span>[</span></span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>markdown</span><span class="punctuation definition string end coffee"><span>'</span></span></span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>md</span><span class="punctuation definition string end coffee"><span>'</span></span></span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>mkd</span><span class="punctuation definition string end coffee"><span>'</span></span></span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>mkdown</span><span class="punctuation definition string end coffee"><span>'</span></span></span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>ron</span><span class="punctuation definition string end coffee"><span>'</span></span></span></span></div><div class="line"><span class="source coffee"><span class="meta brace square coffee"><span>]</span></span></span></div></pre>

<h2>
<a name="bundle-external-resources" href="creating-a-package.html#bundle-external-resources"></a>Bundle External Resources</h2>

<p>It's common to ship external resources like images and fonts in the package, to
make it easy to reference the resources in HTML or CSS, you can use the <code>atom</code>
protocol URLs to load resources in the package.</p>

<p>The URLs should be in the format of
<code>atom://package-name/relative-path-to-package-of-resource</code>, for example, the
<code>atom://image-view/images/transparent-background.gif</code> would be equivalent to
<code>~/.atom/packages/image-view/images/transparent-background.gif</code>.</p>

<p>You can also use the <code>atom</code> protocol URLs in themes.</p>

<h2>
<a name="writing-tests" href="creating-a-package.html#writing-tests"></a>Writing Tests</h2>

<p>Your package <strong>should</strong> have tests, and if they're placed in the <em>spec</em>
directory, they can be run by Atom.</p>

<p>Under the hood, <a href="http://jasmine.github.io">Jasmine</a> executes your tests, so you can assume that any DSL
available there is also available to your package.</p>

<h2>
<a name="running-tests" href="creating-a-package.html#running-tests"></a>Running Tests</h2>

<p>Once you've got your test suite written, you can run it by pressing
<code>cmd-alt-ctrl-p</code> or via the <em>Developer &gt; Run Package Specs</em> menu.</p>

<p>You can also use the <code>apm test</code> command to run them from the command line. It
prints the test output and results to the console and returns the proper status
code depending on whether the tests passed or failed.</p>

<h2>
<a name="publishing" href="creating-a-package.html#publishing"></a>Publishing</h2>

<p>Atom bundles a command line utility called <a href="https://github.com/atom/apm">apm</a> which can be used to publish
Atom packages to the public registry.</p>

<p>Once your package is written and ready for distribution you can run the
following to publish your package:</p>

<pre lang="sh"><code>cd my-package
apm publish minor
</code></pre>

<p>This will update your <code>package.json</code> to have a new minor <code>version</code>, commit the
change, create a new <a href="http://git-scm.com/book/en/Git-Basics-Tagging">Git tag</a>, and then upload the package to the
registry.</p>

<p>Run <code>apm help publish</code> to see all the available options and <code>apm help</code> to see
all the other available commands.</p>

<h2>
<a name="included-libraries" href="creating-a-package.html#included-libraries"></a>Included Libraries</h2>

<p>FIXME: Describe `require 'atom'</p>

<p>In addition to core node.js modules, all packages can <code>require</code> the following
popular libraries into their packages:</p>

<ul>
<li><a href="http://atom.io/docs/v0.60.0/as%20%60require%20'space-pen'%60">SpacePen</a></li>
<li><a href="http://atom.io/docs/v0.60.0/as%20%60require%20'jquery'%60">jQuery</a></li>
<li><a href="http://atom.io/docs/v0.60.0/as%20%60require%20'underscore'%60">Underscore</a></li>
</ul><p>Additional libraries can be found by browsing Atom's <em>node_modules</em> folder.</p>
    </div>
    <div class="column sidebar documents-toc">
      <select class="js-doc-version-switcher version-switcher">
  <option value="v0.69.0">v0.69.0</option>
<option value="v0.68.0">v0.68.0</option>
<option value="v0.67.0">v0.67.0</option>
<option value="v0.66.0">v0.66.0</option>
<option value="v0.65.0">v0.65.0</option>
<option value="v0.64.0">v0.64.0</option>
<option value="v0.63.0">v0.63.0</option>
<option value="v0.62.0">v0.62.0</option>
<option value="v0.61.0">v0.61.0</option>
<option selected="selected" value="v0.60.0">v0.60.0</option>
<option value="v0.59.0">v0.59.0</option>
<option value="v0.58.0">v0.58.0</option>
<option value="v0.57.0">v0.57.0</option>
<option value="v0.56.0">v0.56.0</option>
<option value="v0.55.0">v0.55.0</option>
<option value="v0.54.0">v0.54.0</option>
<option value="v0.53.0">v0.53.0</option>
<option value="v0.51.0">v0.51.0</option>
<option value="v0.50.0">v0.50.0</option>
<option value="v0.49.0">v0.49.0</option>
<option value="v0.48.0">v0.48.0</option>
<option value="v0.47.0">v0.47.0</option>
<option value="v0.46.0">v0.46.0</option>
<option value="v0.45.0">v0.45.0</option>
<option value="v0.44.0">v0.44.0</option>
<option value="v0.41.0">v0.41.0</option>
<option value="v0.40.0">v0.40.0</option>
<option value="0.52.0">0.52.0</option>
</select>


      <ul class="navigation">
        <li><a href="" class="is-selected">Documentation</a></li>
        <li><a href="../api/v0.60.0/api/index.html">API</a></li>
      </ul>

      <hr />

      <form accept-charset="UTF-8" action="/docs/v0.60.0/search" method="get"><div style="margin:0;padding:0;display:inline"><input name="utf8" type="hidden" value="&#x2713;" /></div>
        <input class="sidebar-search-field" id="q" name="q" placeholder="Search documentation" type="text" value="" />
</form>
      <h2>
<a name="guides" href="creating-a-package.html#guides"></a>Guides</h2>

<ul>
<li><a href="getting-started.html">Getting Started</a></li>
<li><a href="customizing-atom.html">Customizing Atom</a></li>
<li><a href="creating-a-package.html">Creating a Package</a></li>
<li><a href="creating-a-theme.html">Creating a Theme</a></li>
<li><a href="publishing-a-package.html">Publishing a Package</a></li>
<li><a href="converting-a-text-mate-bundle.html">Converting a TextMate Bundle</a></li>
<li><a href="converting-a-text-mate-theme.html">Converting a TextMate Theme</a></li>
<li><a href="contributing.html">Contributing</a></li>
</ul><h3>
<a name="advanced-topics" href="creating-a-package.html#advanced-topics"></a>Advanced Topics</h3>

<ul>
<li><a href="advanced/configuration.html">Configuration</a></li>
<li><a href="advanced/keymaps.html">Keymaps</a></li>
<li><a href="advanced/serialization.html">Serialization</a></li>
<li><a href="advanced/view-system.html">View System</a></li>
</ul>
    </div>
  </div>
</div>


    <div class="footer-pad"></div>
  </div>

  <footer>
  <div class="footer">
    <div class="wrapper">
      <ul class="footer-left">
        <li><a href="../../terms.html">Terms of Use</a></li>
          <li><a href="http://atom.io/login">Sign in</a></li>
      </ul>

      <div class="footer-right">
        <a href="https://github.com"><span class="octicon octicon-code"></span> with <span class="octicon octicon-heart"></span> by <span class="octicon octicon-logo-github"></span></a>
      </div>
    </div>
  </div>
</footer>

</body>
</html>
